---
id: api
title: API
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

LLMStack provides a HTTP API that allows you to programmatically interact with the platform. This API can be used to integrate AI experiences into your existing applications or to build new applications on top of LLMStack.

LLMStack supports both streaming and non-streaming APIs for running apps. Streaming API allows you to stream output of the app in real-time. Non-streaming API allows you to run the app and get the output once the app is finished running. Below is the API endpoint for running apps:

:::info
Replace `<app_uuid>` with the UUID of the app you want to run. You can find the UUID of the app in the url of the app builder page.
:::

```
POST /api/apps/<app_uuid>/run
```

## Request body

Below is the format of request body for running apps:

```json
{
  "input": {
    <INPUT_KEY_VALUE_JSON>
  },
  "stream": true
}
```

`INPUT_KEY_VALUE_JSON` is a JSON object with input keys and values. For example, if the app has two input fields `file` and `question`, the request body will look like:

```json
{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": true
}
```

`stream` is a boolean value that indicates whether to stream output of the app or not. If `stream` is set to `true`, the API will stream output of the app in real-time. If `stream` is set to `false`, the API will wait for the app to finish running and return the output once the app is finished running.

## Response body

Below is the format of response body for running apps:

```json
{
  "session": {
    "id": "<session_id_value>"
  },
  "output": {
    <OUTPUT_KEY_VALUE_JSON>
  },
}
```

## Authentication

All API requests must be authenticated using a token. You can find the token in `Settings` page. This token must be passed in the `Authorization` header of the request with `Token:` prefix.

## App Session

Depending on the processors used in an app, LLMStack app can retain information between requests using sessions. For example, if you use `Promptly / Text Chat` or `OpenAI / ChatGPT` processors with history enabled, the app will retain the chat history between requests. This allows you to build apps that can remember information from previous requests. In order to use sessions from API, you will need to include `session_id` in the requests. You can find the session id in the response of the API request. Below is an example of how to use `session_id` in the API request:

```
POST /api/apps/<app_uuid>/run/<session_id>
```

## Examples

Below are examples of how to use API to run apps.

### Streaming API

<Tabs>
<TabItem value="python" label="Python">

```py
import requests

PROMPTLY_TOKEN = '<promptly_token>'
url = 'http://localhost:3000/api/apps/<app_uuid>/run'

payload = {
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": True,
}
headers = {
  "Content-Type": "application/json",
  "Authorization": "Token " + PROMPTLY_TOKEN,
}

response = requests.post(url, headers=headers, json=payload, stream=True)
for line in response.iter_lines():
  if line:
    print(line.decode('utf8'))
```

</TabItem>
  <TabItem value="cURL" label="cURL">

```bash
curl --location --request POST \
'http://localhost:3000/api/apps/<app_uuid>/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <promptly_token>' \
--data-raw '{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": true
}'
```

  </TabItem>
  <TabItem value="javascript" label="JavaScript">

```js
const axios = require("axios");

const url = "http://localhost:3000/api/apps/<app_uuid>/run";
const PROMPTLY_TOKEN = "<promptly_token>";
const payload = {
  input: {
    file: "<file_value>",
    question: "<question_value>",
  },
  stream: true,
};
const headers = {
  "Content-Type": "application/json",
  Authorization: "Token " + PROMPTLY_TOKEN,
};
axios
  .post(url, payload, { headers, responseType: "stream" })
  .then((response) => {
    response.data.on("data", (line) => {
      if (line) {
        console.log(line.toString("utf8"));
      }
    });
  })
  .catch((error) => {
    console.error(error);
  });
```

  </TabItem>
</Tabs>

### Blocking API

<Tabs>
<TabItem value="python" label="Python">

```py
import requests

PROMPTLY_TOKEN = '<promptly_token>'
url = 'http://localhost:3000/api/apps/<app_uuid>/run'

payload = {
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": False,
}
headers = {
  "Content-Type": "application/json",
  "Authorization": "Token " + PROMPTLY_TOKEN,
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text.encode('utf8'))
```

</TabItem>
  <TabItem value="cURL" label="cURL">

```bash
curl --location --request POST \
'http://localhost:3000/api/apps/<app_uuid>/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <promptly_token>' \
--data-raw '{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": false
}'
```

  </TabItem>
  <TabItem value="javascript" label="JavaScript">

```js
const axios = require("axios");

const url = "http://localhost:3000/api/apps/<app_uuid>/run";
const PROMPTLY_TOKEN = "<promptly_token>";
const payload = {
  input: {
    file: "<file_value>",
    question: "<question_value>",
  },
  stream: false,
};
const headers = {
  "Content-Type": "application/json",
  Authorization: "Token " + PROMPTLY_TOKEN,
};

axios.post(url, payload, { headers: headers }).then((response) => {
  console.log(response.data);
});
```

  </TabItem>
</Tabs>
